R Markdown consists of an amazing ecosystem of R packages to produce many types of technical content. Its signature capability is that is can run R code and print the code along with its results and nicely formatted prose.
To understand R Markdown, we need to learn about three new things:
Markdown, a very lightweight text formatting language.
Code chunks, which allow us to incorporate R code that can be executed and whose results we can display in text, figures, and tables.
The YAML header, which encodes metadata about the output, such as the desired output format and specific formatting features.
We’ll focus on HTML page output, but will glimpse at the many possibilities for the output format: with R Markdown, it is possible to create not just technical reports, but also slide decks, websites, books, scientific articles, and so on.
At the core of the R Markdown ecosystem is the rmarkdown package. We need to install this but don’t need to load it:
install.packages("rmarkdown")
Inside your directory for Code Club, create a directory for this week:
dir.create('S07')
Before we go into details, let’s first see a quick demonstration of what we are talking about:
Go to File => New File => R Markdown, change the Title to “Markdown demo”, and click OK.
Take a look at the R Markdown document, and notice that there seems to be some sort of header (=> YAML), followed by R code wrapped in strange constructs with backticks (=> Code chunks), and plain written text (=> Markdown).
Before we can create output, we need to save the document. Click the Save button and save the files as demo.Rmd inside your newly created directory.
Now click the Knit button in one of the top bars, and a document should show up in a pop-up or the Viewer pane. This is the rendered output from the R Markdown document.
Notice that the YAML header is not printed, at least not verbatim, while some of the code is printed, and we also see code output including a plot!
This is what the raw and rendered output look side-by-side:
We’ll now talk about Markdown, code chunks, and the YAML header in turn.
Markdown is a very lightweight language to format plain text files, which evolved from simple in-line formatting applied in emails before those started using HTML.
Need to emphasize a word without being able to make it italic or bold? How about adding emphasis with asterisks *like so*?
| Syntax | Result |
|---|---|
| # My Title | Header level 1 (largest) |
| ## My Section | Header level 2 |
| ### My Subsection | Header level 3 – and so forth |
| *italic* or _italic_ | italic |
| **bold** or __bold__ | bold |
[Markdown Guide](markdownguide.org) |
Markdown Guide (Link with custom text) |
|  | Figure |
| - List item | Unordered (bulleted) list |
| 1. List item | Ordered (numbered) list |
`inline code` |
inline code |
``` …code… ``` |
Generic code block (for formatting only) (Alternative syntax: 4 leading spaces.) |
```r …code… ``` |
r code block (for formatting only) |
--- |
Horizontal rule (line) |
To see this formatting in action, see below an example of a raw Markdown file on the left, and its rendered (formatted) output on the right: